// four services, one ledger
POS-System documentation
A point-of-sale and inventory platform split into four independent applications — a shared backend, an admin console, a till for sales staff, and a console for the warehouse. This page covers architecture, roles, setup, and the data rules that hold it together.
01
The four applications
:5000
Backend
Handles every API call, authentication, and database read/write. Nothing else in the system talks to the database directly.
pos-backend/
:8080
Admin Panel
Full control surface — products, customers, users, invoices, inventory, reports, and settlements.
rtl-admin-dashboard/
:3000
Sales System
What a seller uses at the counter: build a cart, apply discounts, print the invoice.
invoice-management-system/
:3001
Warehouse System
Add or subtract stock with a reason attached, and flag items running low.
invoice-inventory-system/
02
Login credentials
| Role | Phone | Password |
|---|---|---|
| Admin | 09121112233 | 123456 |
| Sales | Created by admin | — |
| Warehouse | Created by admin | — |
| Sales Admin | Created by admin | — |
03
Role permissions
04
Core features
Products & inventory
- Optional unique product code, barcode support
- Units: bottle, carton, liter — carton quantity configurable
- Unit and carton pricing auto-calculated
- Stock minimums and in/out-of-stock status
Customers & settlements
- Purchase history and running statistics
- Debt calculation and partial-payment settlement
- Payment history per customer
Invoicing
- Customer search or on-the-fly creation
- Item and total discounts
- Draft watermark for regular sellers, printed with product codes
Reporting
- Sales by day, week, month
- Top 5 customers, seller commission at 4%
- Excel and PDF export
05
Currency handling
One amount, three representations depending on where it surfaces.
STORED
Rial (IRR)
→
ON SCREEN
Toman (÷10)
→
PRINTED
Rial, labeled
06
Setup
# clone
git clone https://github.com/here-is-leo/pos-system.git
cd pos-system
# backend — :5000
cd pos-backend && npm install
npx prisma generate
npx prisma migrate dev --name init
npm run dev
# admin — :8080
cd ../rtl-admin-dashboard && npm install && npm run dev
# sales — :3000
cd ../invoice-management-system && npm install && npm run dev
# warehouse — :3001
cd ../invoice-inventory-system && npm install && npm run dev
07
Key API endpoints
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/auth/login | User login |
| GET | /api/products | List products |
| POST | /api/invoices | Create invoice |
| POST | /api/invoices/:id/finalize | Finalize invoice |
| POST | /api/inventory/add | Add stock |
| POST | /api/inventory/subtract | Subtract stock |
| GET | /api/customers/with-debt | Customers with outstanding debt |
| POST | /api/payments | Record a payment |
08
Stack & security
Technology
- Node.js + Express, SQLite via Prisma
- React + Vite + TanStack Router, Next.js 16 (×2)
- Tailwind CSS + shadcn/ui, Recharts, XLSX, jsPDF
Security
- JWT auth, 7-day expiry · bcrypt password hashing
- Rate limiting, captcha after 3 failed attempts
- Role-based access, CORS restricted to allowed domains